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API 文档 缺陷 自动 检测 和 修复 方法 
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摘 要 : 应 用 程序 编程 接口 (application programming interface, APD 在 软件 开发 中 起 着 非常 关键 的 作用 ， 而 API 文档 的 
质量 会 严重 影响 开发 人 员 对 API 的 使 用 。 为 了 完善 API 文 档 ， 提 出 了 基于 程序 静态 分 析 和 自然 语言 处 理 的 自动 检测 和 
修复 API 文档 缺陷 的 方法 ， 该 方法 能 自动 检测 和 修复 API 文档 缺陷 。 实 验 中 ， 缺 陷 检 测 结果 的 准确 率 和 召回 率 分 别 达 
到 74.6% 和 81.4%， 能 够 较为 准确 地 检测 到 java API 的 文档 缺陷 。 在 进一步 的 实验 中 ， 还 对 API 文档 的 修复 功能 进行 
了 评估 ， 结 果 表 明生 成 的 文档 正确 且 简 洁 ， 可 以 有 效 地 修复 API 文 档 缺 陷 。 
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Novel approach to automatically detect and repair defective API documentation 
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Abstract: Application Programming Interface (APD play an important role with respect to software development. Particularly, 
the quality of API documentation tends to have a Severe impact on the use of APIs for developers. In this paper, for improving 
API documentation, a novel approach is proposed to automatically detect and repair defective API documentation by adopting 
techniques of program static analysis and natural language processing. Across empirical studies, the proposed approach gives a 
precision of 74.6% and a recall of 81.4%, which demonstrates that the approach can accurately detect the defective 
documentation in javaAPIs. For further experiments, the function ofrepair recommendation for API documentation is evaluated. 
The results indicate that the generated recommendations are correct and Succinct, and can repair API documentation effectively. 
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而 , 由 于 程序 员 的 下 漏 和 软件 维护 升级 等 原因 的 存在 , 导致 API 


0 引言 文档 存在 缺陷 的 现象 时 常 发 生 [#3。 这 些 缺 陷 文 档 的 存在 会 使 得 

随 着 计算 机 应 用 的 不 断 深化 , 软件 的 需求 和 规模 不 断 增 加 。 开发 人 员 在 使 用 API 时 陷入 困境 , 阻碍 其 对 API 的 理解 并 影响 
如 何 快速 高 效 的 完成 软件 开发 成 为 软件 行业 的 追求 目标 。 有 效 软件 的 性 能 &I0。 例 如 : 在 com.sun.java 仅 .你 ml.BeanAdapter 类 
的 复 用 是 提高 软件 开发 效率 、 降 低 开 发 成 本 的 重要 方式 ,其 中 ， 中 的 get(Object target, Class<?> sourceType, String key) 方 法 中 ， 
应 用 程序 编程 接口 (API) 复 用 是 最 有 效 的 手段 之 一 叫 。 开 发 人 对 于 参数 key 的 描述 仅 为 “The property name.” 但 是 如 果 给 参数 
员 无 须 了 解 API 的 底层 实现 或 理解 其 内 部 工作 机 制 的 细节 ， 只 key 传 入 一 个 空 值 null， 则 会 抛 出 一 个 NullPointerException 的 
需 正 确 利 用 开放 的 函数 接口 ， 即 可 实现 相应 的 功能 ， 从 而 提高 异常 。 经 过 分 析 发 现 ， 在 get0 方 法 调用 到 它 类 中 的 
了 软件 的 开发 效率 。 getStaticGetterMethod(Class<?> sourceType, String key, Class<?> 

快速 正确 的 理解 API 是 使 用 API 的 前 提 , 如 果 理 解 API 花 targetType) 方 法 时 ， 有 以 下 约束 条 件 : 如 果 参 数 key 为 null， 则 
费 的 时 间 过 长 甚至 超过 了 重新 编写 类 似 功 能 代码 所 需 的 时 间 ， 抛 出 异常 。 而 get0 方 法 会 直接 把 参数 key 的 值 传 入 
则 失去 了 使 用 API 的 意义 外 。API 文档 在 帮助 开发 人 员 正 确 使 。 getStaticGetterMethod() 方 法 , 从 而 引起 了 该 异常 。 显 然 , 在 get0 
用 API 中 起 着 至 关 重 要 的 作用 中 。API 文档 通过 说 明 API 的 使 方法 的 文档 中 应 该 存在 关于 该 异常 的 描述 ， 以 避免 开发 人 员 触 
用 情境 ， 如 输入 信息 描述 、 版 本 信息 、 参 数 约束 条 件 等 ， 使 得 发 该 异常 ， 导 致 程序 出 错 。 因 此 ， 完 善 的 API 文档 对 于 开发 人 


开发 人 员 遵 循 这 些 规 


I 而 避免 在 使 用 API 时 出 现 错误 上 1。 然 。 员 而 言 是 非常 重要 的 。 
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当前 ， 关 于 API 文档 缺陷 检测 的 研究 较 少 ， 其 中 文献 [11， 
12] 将 NLP 运用 到 java 文档 中 。 文 献 [13] 提 出 了 一 种 结合 自然 


语言 处 理 和 代码 分 析 技 术 来 检测 API 文档 错误 的 方法 。 文 献 [14] 
就 文档 中 对 API 参数 约束 的 描述 进行 了 相关 研究 , 基于 文献 [15] 


对 文档 中 的 约束 类 型 进行 的 调查 ， 将 参数 约束 类 型 分 为 四 类 ， 
分 别 为 空 值 禁止 , 空 值 多 许 ， 类 型 限制 和 取 值 限制 。 文 献 [16] 提 


出 了 一 种 利用 Stack Overflow 来 提高 API 文档 质量 的 方法 ， 通 


过 收集 零散 的 信息 来 为 开发 人 员 提 供 更 全 面 的 支持 。 同 样 ， 在 


中 介绍 了 一 种 将 来 自在 线 网 站 的 源 代码 实 人 


连接 到 API 文 档 


的 方法 。 本 文 针 对 的 研究 问题 虽然 与 他 们 不 同 


的 分 析 技 术 。 


， 但 借鉴 了 他 们 


本 文 是 对 已 有 工作 进行 的 扩展 09， 扩 展 内 容 体现 在 以 下 几 


个 方面 : a) 实 验方 法 针对 的 约束 类 型 , 由 空 值 多 许 、 空 值 禁 


取 值 限制 ， 扩 展 为 空 值 允许 、 空 值 禁 止 、 取 值 限制 、 类 型 限制 
四 种 , 使 本 方法 更 具有 普 适 性 ;b) 通 过 对 API 文档 进行 自然 语言 
处 理 ， 理 解 其 语义 信息 ， 定 义 并 总 结 了 64 条 启发 式 语义 规则 ， 
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王 长 志 ， 等 : API 文 档 缺 陷 自动 检测 和 修 法 


首先 ,利用 程序 静态 分 析 , 从 代码 中 提取 抛 异常 时 的 约束 条 件 ， 
即 “evertType == null”。 其 次 ， 对 API 文档 进行 处 理 ， 提 取 与 
异常 相关 的 约束 信息 ， 在 本 例 中 ， 从 API 文档 里 可 以 提取 到 有 
关 evertType 为 null 的 信息 。 将 两 者 提取 的 信息 进行 对 比 ， 关 
断 是 否 一 致 。 显 然 在 本 例 中 ， 两 者 约束 一 致 ， 文 档 描 述 正确 。 
假设 当 该 文档 中 不 存在 这 个 描述 时 ， 则 文档 是 有 缺陷 的 ， 需 要 
对 其 进行 补 全 修复 。 为 此 ， 本 文 定义 了 相关 的 语义 规则 ， 利 用 
从 代码 中 提取 到 的 约束 条 件 ， 完 成 文档 修复 工作 。 根 据 规则 ， 
该 约束 条 件 生 成 的 文档 为 :“*@throws NullPointerException 让 
evertType is null”。 
1.2 方法 框架 

本 文 提出 了 一 种 文档 缺陷 自动 检测 和 修复 技术 。 图 2 给 出 
了 该 方法 的 整体 流程 图 。 该 方法 主要 由 四 个 部 分 构成 : 
a 代码 约束 条 件 提取 。 该 部 分 利用 程序 静态 分 析 技 术 ， 获 


i 


从 文档 中 提取 相对 应 的 约束 信息 。 相 比 于 之 前 方法 ， 大 大 增加 


了 文档 约束 信息 的 准确 率 和 履 盖 率 ;c) 通过 使 用 约束 求解 器 对 
代码 和 文档 的 约束 条 件 进 行 检测 ， 使 得 检测 结果 更 加 准确 ;，d) 
根据 检测 到 的 文档 缺陷 ， 本 文 新 增加 了 缺陷 修复 方法 。 


1 ”方法 概述 


与 基本 方法 ， 之 后 给 出 基于 程序 静态 分 析 的 
API 文档 缺陷 方法 的 总 体 框架 。 
1.1 示例 说 明 


的 方法 。 其 中 在 validateEventType() 方 法 中 ， 
null” 时 ， 有 有 异常 抛 出 。 显 然 ， 因 为 addEv 


validateEventType() 方 法 ， 在 addEventFilter() 方 法 中 ， 如 果 


图 1 中 是 com.sun.javafx.event.EventHandler- Manager 类 中 


本 节 首 先 通 过 一 个 实际 例子 来 更 为 直观 的 说 明 本 文 的 目标 


自动 检测 和 修复 


当 “evertType == 


取 方 法 之 间 的 调用 关系 ， 结 合 调用 关系 ， 提 取 程 序 抛 出 异常 时 
的 约束 条 件 。 
b) 文 档 约 束 条 件 提 取 。 根 据 总 结 的 启发 式 语义 规则 ， 提 取 
文档 中 关于 异常 信息 描述 的 约束 条 件 。 

0o) 代 码 与 文档 约束 条 件 对 比 。 将 代码 和 文档 中 的 约束 条 件 
转换 为 一 阶 逻 辑 表 达 式 (first order logic, FOL )， 利 用 Z3 求解 器 
进行 对 比 ， 获 取 逻 辑 验 证 结果 ， 若 两 者 不 一 致 ， 则 认为 文档 有 
缺陷 ， 需 要 进行 补 全 。 

d) 生 成 文档 缺陷 报告 及 修复 建议 : 本 文 根 据 FOL 的 格式 ， 
设 定 了 FOL 生成 自然 语言 的 语义 规则 。 根 据 代码 中 提取 的 约束 
条 件 FOL 和 语义 规则 , 将 代码 约束 条 件 转换 为 自然 语言 推荐 给 
用 户 ， 使 得 用 户 可 以 对 文档 进行 补 全 。 


= 


代码 约束 | 一 一 一 


代码 | ,| si 分析 结合 调用 关 | 。 ,| 代码 的 约束 


系 分 析 条 人 


entFilterO 调 用 了 


evertType 赋值 为 null 时 ， 该 异常 也 会 抛 出 。 因 此 ,为 防止 开发 
人 员 触 发 该 异常 ，API 文档 中 有 关于 该 异常 的 描述 :“@throws 


NullPointerException if the event type or filter is 


/** 


* Registers an event filter in {@code EventHandlerM: 


* @param <T> the specific event class of the filter 
* @param eventType the type of the events to receiv 
* @param eventFilter the filter to register 
* @throws NullPointerException if the event type or 
wp 
public final <T extends Event> void aaa 
final EventType<T> eventType, 
final EventHandler<? super T> eventFilter) { 
validateEventType (eventType); 
validateEventFilter(eventFilter); 


final CompositeEventHandler<T> compositeEventHanm 
createGetCompositeEventHandler (eventType 


compositeEventHandler .EGGEAEREEIIEEE(eventFilter 
} 


图 1 从 JDK 中 选取 的 示例 


null”。 


anager}. 


e by the filter 


filter is null 


dler = 
); 


) 


本 文中 的 研究 方法 即 检测 代码 中 抛 异常 的 约束 条 件 在 文档 
中 是 否 存在 正确 描述 ， 如 果 不 存在 描述 ， 则 文档 存在 缺陷 ， 
对 文档 进行 修复 。 为 解决 这 一 问题 ， 本 文 使 用 程序 静态 分 析 和 
基于 模板 的 自然 语言 处 理 技 术 ， 具 体 过 程 分 为 以 下 几 个 步 又 : 


件 
间 的 调 
启发 式 
5 es E 从 | 修复 建议 
程序 的 源 代码 I 
4, 
a . 语义 理解 规 文档 的 约束 | 语义 规 
avadoc "| 语句 预 处 理 则 匹配 "| 条 件 则 


图 2 文档 缺陷 检测 修复 技术 的 整体 流程 

在 现 有 工作 中 ， 本 方法 主要 检测 空 值 禁止 、 空 值 人 多 许 、 取 
值 限制 和 类 型 限制 四 种 约束 类 型 是 否 有 文档 缺陷 [13]， 以 下 是 
关于 四 种 类 型 的 介绍 : 

a) 空 值 禁 止 。 空 值 null 不 能 作为 参数 传递 给 该 方法 。 当 参 
数 传 入 空 值 时 ， 会 有 异常 殷 出 ， 如 NullPointerException 。 

b) 空 值 多 许 。 与 空 值 禁止 相反 ， 空 值 null 可 以 作为 参数 传 
递 给 该 方法 ， 此 时 没有 异常 抛 出 。 因 为 参数 为 null 是 一 种 比较 
特殊 的 情况 ， 因 此 需要 在 文档 中 予以 描述 。 

co) 取 值 限制 。 方 法 参数 必须 符合 某 一 取 值 范围 ， 如 果 超 出 
这 一 范围 ， 则 会 有 异常 殷 出 。 

9 类 型 限制 。 类 似 于 取 值 限制 ， 方 法 参数 必须 属于 某 些 类 
型 ， 如 果 不 属 于 这 些 类 型 ， 则 会 抛 出 异常 。 由 于 面向 对 象 程序 
语言 具有 继承 的 特性 ， 因 此 在 API 文档 中 也 必须 对 此 类 作出 准 


:201809.00131v1 


chinaXiv 


录用 稿 
2 ”方法 实现 
2.1 约束 条 件 提取 

对 于 API 来 说 ， 异 常 抛 出 的 约束 条 件 不 仅 存在 于 其 本 身 方 
法 体 中 ， 也 存在 于 它 的 调用 方法 之 中 ， 因 此 代码 约束 条 件 提 取 
分 为 以 下 三 步 : a) 方 法 调用 关系 分 析 ， 分 析 方 法 之 间 的 调用 关 


系 ， 建 立方 法 间 调 用 关系 集 


合 ;b) 方 法 约束 条 件 提取 ， 构 建 方法 


体 的 抽象 语法 树 ， 提 取 方 法 体 中 的 约束 信息 ;c) 考 虑 调用 关系 是 
否 存在 ， 构 建 完 整 的 约束 条 件 信息 
2.1.1 调用 关系 分 析 


因为 本 文 主要 关注 


信息 。 


方法 参数 的 约束 条 件 是 否 在 文档 中 予以 


述 ， 因 此 在 分 析 


component) 方 法 中 ，Component 


java.awt.Container 3 


Cc， 


前 用 关系 时 ， 仅 关注 直接 传 参 类 型 的 。 例 如 


在 javax.swing.JTabbedPane 类 的 addTab(String title, Component 


类 型 的 参数 最 终 传递 给 了 
类 中 checkNotAWindow(Component comp) 方 


法 从 而 引发 了 异常 。 这 种 即 为 存在 参数 传递 的 调 ) 
首先 ， 解 析 API 源码 ， 
eclipse 的 call hierarchy 模块 进行 调用 关系 分 析 。 有 具体 分 为 以 下 
几 步 : 获取 方法 的 m 的 参数 列表 Pm， 如 果 方法 冲 调 


获取 方法 c 的 参 


关系 。 
的 抽象 语法 树 ， 再 通过 


提取 方法 m 


王 长 志 ， 等 : 


ChinaXiv 合 作 
API 文 档 缺陷 le, 


/* J1f the statement contains a method call of n, check the invoked method 


recursively */ 


10 else if isMethod(stm) ^ (stm’s args GE ms list) then 


/*n is the callee of m in stm */ 


11 mList «— n:getBody/(); 


12 infoList «—infoList U expExtractor(mList; dep - 1); 


2.1.3 约束 条 件 信 息 整 合 

根据 第 二 
先 删除 与 参数 无 关 的 异常 
ExcepInfo(m;P;t;c), 如 果 异 常 触发 条 


步 中 获得 的 每 个 方法 m 的 ExcepInfom 列表 。 
约束 信息 
牛 c 没 有 P 中 的 参数 出 现 ， 


首 
， 即 对 于 每 个 


则 此 异常 信息 与 参数 无 关 ， 这 种 ! 


青 况 不 在 本 文 讨论 范围 之 内 ， 


将 此 条 ExcepInfo 删除 。 其 次 ， 根 据 第 


步 获得 的 调用 关 


系 自 


A 


合 ， 对 于 集合 中 的 每 个 方法 ， 


逐 层 递归 获取 其 异常 信息 。 即 对 
于 方法 m 和 方法 n，m 调用 n， 如 果 (n;P;t;c) 中 约束 条 ff 


牛 c 与 方 


的 参数 p 


法 m 


(n;P;t;c) 要 被 归并 到 ExcepInfom 列表 中 。 这 相 


m 完整 的 异常 约束 条 件 信 息 。 


] 了 方法 
如 果 满 足 Pm 与 Pc 的 交集 不 为 


ed 


数列 表 Pc。 


企 


入 


g， 则 方法 e 与 方法 m 存在 直接 传 参 的 调 


关系 ， 将 方法 c 放 


ee 


方法 


件 提 取 


对 于 API 的 每 个 public 方法 m， 通 过 遍历 


m 的 调用 关系 集合 之 中 。 
2.1.2 约束 条 


调用 关系 分 析 形 成 闭环 ， 需 要 设 
中 设置 的 阔 值 为 4。 
2.2 文档 约束 条 件 提 取 


关 ， 则 方法 m 也 能 触发 方法 n 


的 这 个 异常 ， 
#， 便 获得 了 方法 


特别 的 ， 在 递归 调 
递归 深度 靖 值 ， 本 文 在 实验 


时 ， 为 防止 


API 文档 对 约束 信息 描述 具有 自然 
现 ， 对 于 相同 的 约束 类 型 


语言 特性 ， 基 于 观察 发 


，API 文档 的 文本 措 


述 通 常 具有 类 似 


的 语法 结构 。 由 于 这 种 共性 


的 存在， 使 


象 语法 树 ， 获 


常 的 约束 条 件 ， 
合 


的 参数 列表 ,t+ 是 


的 throw 语 品 ]， 收集 有 关 的 异常 中 信息 人， 
将 每 个 方法 
ExcepInfom (m;P;t;c)， 其 中 m 是 当前 方法 的 名 称 ， 


可 漳 查 找 触发 该 
m 的 异 常 信 | 息 存 傅 为 个 元 祖 的 
P 是 方 


言 处 理 的 思想 和 方法 ， 对 文档 进 
中 ， 本 文 利用 Stanford Parse 对 语 
斯 坦 福 大 学 开发 的 一 款 
词性 标注 、 


开源 自然 语言 处 理 框 


一 


异常 的 类 型 ，c 是 异常 的 触发 条 件 。 提 取 异 


约束 条 件 信息 的 伪 代 码 如 下 所 示 ; 


代码 中 约束 条 件 的 提取 算法 : 


Data: stmList:AST statement block of a method m, and dep: integer 


Result: infoList:list of exception information,which records the folw- 


exception tuples,i.e,(m;P;t;c) 


1 infoList <«— & 


2 


if dep >= 0 then 


3 foreach stm € stmList do 


/A* 1stm throws an exception, records all information in a tuple and add 


to the list */ 


4 if isThrowable(stm) then 


5 infoList 二 infoList U {flm; P;t;c)jP: 


6 parameter, t : exceptiontype, c : condition} 


/* Recursively invoke itself, in case of composite statement */ 


7 else if isComposite(stm) then 


8 List subList 二 (Block)stm:getBody(); 


9 infoList — 


infoList U expExtractor(subList; dep); 


得 可 以 通过 基于 
区 其 约束 条 件 。 其 
句 进行 处 理 。Stanford Parse 是 

架 。 该 框架 提供 了 
句法 解析 和 词 项 依存 关系 分 析 等 功能 。 英 
语 进 行 处 理 ， 还 能 对 中 文 和 德 文 等 语言 进行 解析 ， 


行 处 理 ， 提 是 


除了 能 对 
功能 强大 。 


在 API 文档 中 ，javadoc 的 每 一 个 @ 代 表 着 一 个 标签 条 目 


不 同 的 标签 类 型 其 描述 的 内 容 也 不 相同 。 如 : 
要 描述 版 本 说 明 信 息 ，@since 指定 程序 


进行 分 析 。 

本 方法 主要 包括 以 下 两 个 步骤 ; 

a) 预 处 理 阶段 。 删 除 句 子 中 一 些 标 记 与 
语法 树 结构 ， 将 含 
个 约束 条 件 的 原子 语句 。 

b) 语 义理 解 。 根 
句 进行 理解 。 
2.2.1 文档 预 处 理 


Ar 


符号 。 
有 多 个 约束 条 件 的 复合 语句 拆 分 为 只 含有 


@version 标签 主 


尺码 最 早 使 用 的 版 本 。 
于 本 文 关 注 点 在 文档 中 对 于 方法 参数 的 约束 条 伯 
主要 对 @exception、@throws 和 @param 这 三 个 标签 中 的 内 容 


件 描述 ， 因 此 


根据 句子 的 


依存 语法 和 启发 式 语义 规则 ， 对 原子 语 


API 文档 虽然 具有 自然 语言 的 特性 ， 但 


其 与 纯 自然 语言 倒 


述 有 所 不 同 ， 它 经 常会 与 代码 的 一 些 标识 符 混在 一 起 。 为 将 文 


上 | 
上 


档 处 理 为 纯 


还 有 一 些 巾 


自然 语言 ， 需 要 对 文档 进行 预 处 至 
的 标题 @exception、@throws 和 @param( 为 喻 这 三 个 要 被 删除 )， 
入 式 的 标记 (如 <code>) 等 ， 都 需 


工作 ， 比 如 标签 


要 被 删除 。 预 处 


录用 稿 


中 


里 时 ， 为 了 不 丢失 有 效 信息 ， 
将 会 被 记录 下 来 进行 保存 。 

在 获得 自然 语句 之 后 ， 由 于 一 个 语句 中 可 能 含有 多 个 约束 
条 件 ， 且 每 个 约束 所 约束 的 行为 也 可 能 不 同 ， 会 对 语句 的 理解 
产生 偏差 ， 因 此 需要 对 语句 进行 拆 分 ， 使 其 变 为 只 含有 一 个 约 


它们 的 标签 类 型 和 后 面 的 参数 都 


即 当 
的 。 


为 文档 是 正确 的 : 


其 中 : 


束 条 件 的 原子 语句 。 本 文 利用 Stanford Parse 对 语句 进行 处 理 ， 


获得 语句 的 语法 树 ， 通 过 分 析 语 法 树 ， 对 语句 进行 拆 分 ， 得 到 
每 个 约束 条 件 的 原子 语句 。 
2.2.2 语义 理解 
文档 预 处 理 后 ， 通 过 对 获得 的 API 文档 的 原子 语句 进行 语 
义 分 析 ， 提 取 其 中 的 约束 条 件 。 基 本 思想 是 根据 句子 的 依存 语 
法 和 人 工 定 义 的 启发 式 语义 规则 ， 对 句子 进行 解析 。 
利用 程序 去 正确 理解 自然 语言 是 一 件 非常 困难 的 事情 ， 但 
对 于 API 文档 ， 由 于 其 专业 性 的 存在 ， 使 得 很 多 文档 具有 相同 
的 句 式 D9P0 。 例 如 : 


javax.swing.BorderFactory 类 中 的 


2.4 


所 以 


言 补 全 到 API 文档 中 。 如 图 


告 髓 
已 


结 ] 


显然 ， 检 测 上 


ChinaXiv 


王 长 志 ， 等 : API 文 档 缺 陷 


代码 与 文档 中 的 约束 描述 
区 式 上 ， 当 两 者 关于 


DD 


api doc 


尺码 中 的 约束 条 件 ， 


ww 代表 


SMT(Sati 


， 将 FOL 有 序 加 入 ， 
否 有 缺陷 ， 并 得 到 API 文档 的 缺陷 报告 。 
缺陷 修复 


不 一 致 时 ， 则 判定 文档 是 


i, 代表 文档 的 约束 条 件 。 
述 公 式 等 于 检测 : (ww Yue)^C 
是 否 可 被 满足 。 根 据 此 公式 ， 利 用 
Theories) 工 


档 是 


获得 逻辑 验证 


早起 增 由 历法 


有 缺陷 


参数 x 的 FOL 满足 如 下 公式 时 ， 则 认 


Vv Dy,,.) 


api 


sfiability Modulo 
结果 ， 检 测 文 


由 于 API 文档 没 
针对 该 缺陷 将 代码 中 的 约束 条 件 
2 所 示 ， 


硅 


createStrokeBorder(BasicStroke stroke,Paint paint) 方 法 对 应 的 
API 文档 中 提 到 ，“if the specified {@code stroke} is {@code 
noll}”， 则 会 抛 出 异常 在 
SwingPropertyChangeSupport 类 中 的 firePropertyChange(final 
PropertyChangeEvent evt) 方 法 , 也 有 类 似 的 描述 , “if {@code evt} 
is {@codenull} ”， 则 抛 出 异常 。 上 述 两 个 例子 都 是 API 文档 中 
提 到 的 参数 不 能 为 空 的 描述 ， 其 句 式 都 为 “[parameter] be/equals 
依存 语法 为 “mark(null-4, if-1),nsubj(null-4, parameter- 
2),cop(null-4, is-3),root(ROOT-0, null-4)”。 利 用 依存 语法 就 可 以 


Javax.swing.event. 


null”， 


解析 到 “parameter == null* 的 约束 条 件 。 因 此 ， 可 以 根据 句 式 ， 
利用 依存 语法 ， 从 类 似 的 描述 中 提取 约束 条 件 信息 。 


基于 此 ,本文 定义 了 识别 特定 
利用 这 些 规则 对 API 文档 进 和 


吉 构 语句 的 启发 式 语义 规则 ， 
J 解析 ， 获 取 文 档 中 的 约束 条 件 。 


通过 对 JDK 中 部 分 API 文档 进行 归纳 总 结 ， 得 到 4 类 共 64 条 
语义 解析 规则 ， 如 表 1 所 示 。 
表 1 启发 式 语义 规则 

规则 类 型 描述 数量 
空 值 禁止 输入 参数 不 能 为 空 20 
空 值 允许 传 入 参数 可 以 为 室 ， 具 有 特殊 意义 11 
取 值 限制 参数 取 值 必须 在 一 定 范围 内 10 
类 型 限制 参数 必须 属于 某 些 类 型 23 

总 计 64 
2.3 约束 条 件 对 比 

在 获得 代码 和 文档 的 约束 条 件 信息 之 后 ， 将 其 转换 为 FOL 
公式 表示 。 在 处 理 过 程 中 ， 定 义 一 组 转换 规则 ， 例 如 : 


“parameter=null” 的 FOL 为 : NullConstraint(parameter;NEG); 
NullConstraint 代表 空 值 约束 ，parameter 代表 参数 ，NEG 代表 
否定 ( 即 参数 为 空 时 有 异常 ) 

获得 代码 和 文档 的 FOL 后 , 利用 可 满足 性 模型 理论 , 对 两 
者 进行 验证 ， 检 测 两 者 逻辑 是 否 一 致 ， 从 而 判断 文档 是 否 有 缺 
陷 。 这 个 判断 基于 的 假设 是 :默认 代码 中 的 约束 描述 是 正确 的 ， 


最 为 简洁 的 语言 描述 作为 模板 , 将 FOL 转换 为 自然 语言 。 共 有 


对 代码 中 的 约束 条 件 信息 
言 息 依据 规则 
于 代码 的 FOL 和 
成 相关 修复 建议 。 本 文 在 归纳 启发 式 语义 规则 时 ， 
了 API 文档 对 于 每 种 约束 的 描述 。 在 生成 文档 时 ， 从 中 选取 


了 准确 描 ; 


引进 行 述 ， 
9 然 语 


缺陷 报 
已 经 总 


睹 二 < 


4 类 11 条 模板 ， 如 表 2 所 示 。 
表 2 缺陷 修复 模板 
规则 类 型 Tags 模板 
If [param] be null 
空 值 禁止 ”@throws If [param1] or [param2] be null 
If [param1], ... , or [paramN] be null 
空 值 允许 ”@param [param] could be null 
If [param] be type of [SpecType] 
取 值 限制 ”@throws 
If [param] be not type of [SpecType] 
If [param] {relation} [value] 
If [param] {relation} [value1], ... , [valueN] 
类 型 限制 ”@throws If [paraml] or [param2] {relation} [value] 


If [param] {relation} [valuel] and {relation} [value2] 


If [param 


{relation} [valuel] or {relation} [value2] 


洁 性 


MacFileNSURL baseDocument) 方 法 中 ， 
NullConstraint(data, NEG) ， 生 成 的 修复 建议 为 


NullPointerException 


H 


考虑 , 对 于 报错 的 统一 使 


的 


Ifdata is null.”。 最终 


createFromDocumentScopedBookmark(byte[] 


提取 的 FOL 为 


生成 的 文档 与 javadoc 相同 , 会 为 其 添加 一 个 标签 , 出 于 简 
j@throws, 对 于 空 值 允许 的 则 使 
jj@param。 例 如 ， 在 com.sun.glass.ui.mac.MacFileNSURL 类 


data, 


“ @throws 


和 4， 缺陷 修复 生成 的 


文档 


3 


检测 
源 代 


与 原 有 API 文档 格式 一 致 ， 具 


实验 分 析 


和 修复 方法 的 有 效 性 及 准确 性 
码 为 实验 对 象 ， 对 本 方法 进行 


,实验 一 将 


验证 。 


良好 的 可 读 性 。 


由 于 JDK 中 的 API 文档 比较 完备 , 为 了 验证 


同时 ， 为 了 进 


所 提 
JDK 部 分 项 


出 的 缺陷 
的 
步 证 


明 方 


guava 项 


法 对 其 他 java API 的 适用 性 ， 


二 > 了 ITA 一 v7 
K 验 二 采 


Google 公司 的 


WA 


实验 平台 为 Intel i7-4790 3.6 GHz 处 理 器 和 32.0 


录用 稿 


GB RAM 的 台式 机 电脑 ， 搭 载 Windows 7 64-bit 操作 系统 ， 使 
j Java 版 本 为 1.8.0_ 25， 使 用 Eclipse Luna-SR2 作为 代码 实现 
于 发 IDE。 
实验 准备 
本 文 以 7 
E 确 


记 


其 


表示 文档 缺陷 存在 
断 是 正确 的 ， 


陷 
为 
方 


的 3 
3.1 


为 准 


的 关 
>» 表 


示 报 出 文档 缺陷 的 情况 中 , 报告 准确 所 


3 


侍 确 率 和 召 


率 来 衡量 方法 的 检测 结果 。 


以 人 工 标 


士 困 
结果 ， 


相关 计算 公式 如 下 : 


TP 


precision = 


F- measure = 


,recall 
TP+FP 


TP+EN 


2 precisionx recall 
x 


precision+ recall 


中 TP 表示 方法 判断 文档 他 


的 情况 


屋 
Ea 
Fy 


陷 存 在 昌 


于 误 判 ，TN 


的 情况 是 真是 存在 的 ，FP 


表示 方法 对 文档 无 缺 


FN 表示 方法 的 ; 


局 判断 。Precision 为 准确 


5 的 比例 。Recall 


如 区 


浴 ， 表示 源 代码 里 
法 检测 出 的 比 侦 


数 ， 是 一 种 对 准 
3.2 实验 1 


对 com.sun、javafx 午 


口 


E 确 率 和 召 


所 有 存在 的 API 文档 缺陷 中 ， 被 实验 
| 。F-measure 是 precision 和 recall 的 调和 平均 
率 进行 综合 考量 的 指标 。 


上 javax.swing 三 个 包 中 的 源 代码 作为 
测试 对 象 进行 了 实验 。 经 过 统计 ， 这 三 个 包 中 ， 代 码 总 行 数 约 


为 134 万 ,共有 4 万 多 种 方法 。 在 这 些 文档 中 , @param、@throw 


和 @exception 三 种 标签 的 总 数 为 21462 条 。 有 具体 统计 情况 如 表 
3 所 示 。 
表 3 实验 1 数据 总 览 
源 代码 包 Com.sun Javafx Javax.swing 总 计 
源 代码 行 数 344.3k 625.4k 372.8k 1342.5k 
方法 数 10125 19807 12601 42533 
@param 2773 7832 8531 19136 
@throws 271 1040 448 1759 
@exception 17 17 533 567 
对 数据 进行 统计 时 ， 首 先 通过 人 工 标记 的 方法 获取 一 个 标 
准 数据 集 ， 文 档 是 否 有 缺陷 以 人 工 判断 为 准 。 共 有 五 名 计算 机 
专业 的 研究 生 对 代码 文档 进行 评估 分 析 , 判断 文档 是 否 有 缺陷 。 
实验 结果 如 表 4 所 示 。 
表 4 实验 1 检测 结果 
约束 类 型 ” 空 值 禁止 ” 空 值 允许 ” 取 值 限制 ”类 型 限制 ”总 计 
TP 179 457 227 42 905 
FP 67 51 183 7 308 
FN 5 27 80 95 207 
准确 率 (%) 72.8 90.0 55.4 85.7 74.6 
召回 率 (%) 97.3 94.4 73.9 30.7 81.4 
F-m(%) 83.3 92.1 63.3 45.2 77.8 


如 表 4 所 示 ， 对 于 不 同 的 约束 类 型 ， 本 文 的 检测 方法 都 能 


取得 较 好 的 效果 , 其 
取 值 限制 


的 7 


F 多 不 清晰 的 


氏 了 取 人 4 


HP 空 值 允许 的 准确 
住 确 率 较 低 ， 仅 有 55.4%。 


率 能 够 达到 90%。 但 是 ， 
经 过 对 实验 结果 的 分 析 


王 长 志 ， 


等 : 


ChinaXiv 合 人 


| 


信人 门 


API 文 档 缺陷 自 动 检 测 和 修复 方法 


javax.swing.AbstractButton 类 的 checkHorizontalKey(int key, 
String exception) 方 法 中 , 若 key 不 为 "LEFT、CENTER RIGHT、 
LEADING 或 TRAILING” 时 , 则 会 有 IllegalArgumentException 


异常 抛 出 。 


但 相应 


的 API 文档 的 描述 为 “@exception 


TllegalAreumentException if key is not one of the legal values listed 


above”。 


由 于 提取 不 到 


但 人 工会 判定 为 
算 作 有 约束 描述 


一 致 。 从 而 降低 
， 却 描述 模 煌 


] 。 在 实验 一 中 
3.3 实验 2 


， 对 正确 


有 效 信息 ， 在 方法 中 会 判定 为 不 一 致 


了 准确 率 。 


但 这 种 文档 昌 可 


以 


至 


， 人 缺陷 检测 准确 


率 较 高 


为 验证 本 方 


guava 项 
其 中 ,guava.com 


@param、@throw 和 


法 的 


目 作 为 测试 对 象 。Guava 


项 目 代码 行 数 约 


@exception 


普 适 性 , 在 实验 2 中 选取 了 Google 公司 
的 一 组 Java 核心 库 ， 


是 该 公司 


E 解 API 起 不 到 任何 作 
， 达 到 74.6%。 


的 


为 16 万 ， 


~ 


有 方法 四 


干 多 个 。 


三 种 标签 的 总 数 为 2276 条 。 


采用 与 实验 


同 


样 的 评判 方式 ， 实 验 结果 如 表 5 所 示 。 


表 5 实验 2 检测 结果 

约束 类 型 ” 空 值 禁 止 ” 空 值 允 许 ” 取 值 限制 ”类 型 限制 ”总 计 
TP 545 8 89 2 644 

FP 37 2 116 1 176 

FN 4 4 24 1 33 

准确 率 (%) 90.5 80.0 43.4 66.7 78.5 
召回 率 (%) 99.3 66.7 78.8 667 95.1 
F-m(%) 94.7 72.3 56.0 66.7 86.0 
在 本 实验 中 共 报 出 文档 缺陷 820 条 ， 其 中 有 644 条 是 准确 
的 ，176 条 误 报 。 实 验 结果 中 出 现 了 与 实验 一 相同 的 问题 ， 即 
取 值 限制 的 准确 率 相对 较 低 。 导 致 这 个 现象 的 原因 有 很 多 ， 其 
中 有 实验 一 提 到 的 原因 。 也 有 如 com.google. 


common.base.Preconditions 类 checkPositionIndexes(int start, int 


end，int size) 方 法 的 文档 中 


有 这 样 的 描述 


“ @throws 


IndexOutOfBoundsException if either index is negative or is greater 
than {@code size},or if {@code end} is less than {@code start} ” 
以 看 做 是 方法 的 这 说 明 参 数 ， 


从 人 为 的 
但 是 在 方法 中 的 
档 没有 描述 。 这 
局 限 性 ， 但 实验 


j 度 “either index” 就 


可 


文档 提取 中 ， 上 出 


的 总 准确 率 达到 


对 java API 的 适 
取得 较 高 的 检测 


性 ， 


3.4 实验 3 

为 了 验证 A 
到 的 缺陷 检测 结 
本 实验 从 中 随机 
源 代码 和 相关 约 


3 分 为 中 立 , 1 分 为 最 差 ， 


限制 的 准确 率 。 例 如 在 


表 6 所 示 。 


准确 率 。 


说 明 本 方法 中 使 


村 别 是 对 


于 提取 不 到 参数 名 ， 


而 认为 文 


用 的 文档 提取 规则 


有 一 定 的 


78.5%， 充 分 证 明 本 实验 方法 


类 型 ， 


于 空 值 约束 的 


PI 文档 缺 
果 ， 对 于 有 缺陷 


小， 


陷 修复 的 质量 ， 利 


抽取 400 条 修复 建议 作为 相 
束 条 件 。 选 取 五 名 计算 机 专业 
条 修复 建议 从 准确 性 、 内 容 充足 性 和 简洁 性 等 四 
分 P09， 评估 修复 建议 的 质量 ， 分 数 为 5 至 


jC 上 EP 


本 方法 能 


页 个 实验 得 


的 文档 生成 对 应 的 4 


本， 并 提供 相应 的 


的 大 


邹 * 


九 


生 ， 对 每 


个 方面 


| 进行 打 


1 1 分 ，5 分 为 最 好 ， 


其 中 每 条 数据 


EF 估 三 次 。 打 分 标 i 


如 


录用 稿 
表 6 修复 文档 质量 评分 标准 
问题 分 数 范 围 
QI1 修复 建议 是 否 准确 的 表示 了 代码 约束 条 件 ? | 
Q2 修复 建议 是 有 利于 帮助 使 用 此 API? 5-1 
Q3 ”修复 建议 是 否 含有 与 代码 约束 条 件 无 关 的 信息 ? 5-1 
Q4 网 复 建议 是 否 简洁 易 懂 ? 5-1 
评估 结果 如 表 7 所 示 . 
表 7 实验 3 评分 结果 : 
结果 Q1 Q2 Q3 Q4 
5 898 558 903 733 
4 153 183 158 261 
3 44 195 56 105 
2 31 188 30 30 
1 74 76 53 a 
平均 分 4.48 3.82 4.53 4.31 


在 所 有 样本 中 ， 评 估 结 果 为 3 分 以 上 的 修复 建议 占 比 为 
88.5%， 结 果 证 明 本 文中 的 修复 方法 对 于 修复 现 有 的 文档 缺陷 
起 着 积极 作用 ， 而 且 ， 除 问题 2 外 ， 平 均 分 都 在 4 分 以 上 。 问 
题 2 分 数 较 低 的 原因 在 于 所 抽取 的 样本 中 本 身 就 有 缺陷 检测 属 
于 误 判 的 数据 ， 对 于 此 类 数据 ， 其 API 本 身 的 文档 可 能 就 有 较 
为 准确 的 描述 ， 因 此 问题 2 得 分 较 低 。 由 评估 结果 说 明 ， 本 实 
验方 法 生成 的 修复 建议 质量 较 高 ， 简 洁 明 了 ， 充 分 地 表述 了 代 
码 中 的 约束 条 件 ， 可 以 有 效 的 修复 API 文档 的 缺陷 。 


| 


~ 


. 


4 ”结束 语 


本 文 首先 以 JDK 的 子 项 目 作为 实验 对 象 进行 实验 。 通 过 实 
验 1 和 2 验证 了 文档 缺陷 检测 和 修复 方法 的 合理 性 和 准确 性 ， 
检测 方法 准确 率 高 ， 修 复方 法 则 能 生成 合理 的 缺陷 修复 建议 ， 


对 文档 进行 良好 的 补充 。 在 实验 2 中 ， 验 证 了 本 方法 对 于 Java 
语言 的 其 他 开源 项 目 同样 适用 。 实 验 结果 标明 对 于 不 同 约束 条 
件 类 型 、 不 同 的 项 目 ， 本 文 所 提出 检测 和 修复 方法 具有 普遍 适 
用 性 ， 并 取得 了 良好 的 实验 结果 。 

今后 还 将 继续 扩展 归纳 实验 中 的 启发 式 语义 规则 ， 进 一 步 
提高 方法 的 准确 性 ， 并 将 开发 实现 该 方法 的 界面 图 形 工具 ， 如 
基于 Eclipse 等 集成 开发 环境 采用 插件 式 开发 C]， 提 供 更 为 用 
户 友 好 的 支持 。 同 时 ， 针 对 使 用 启发 式 语义 规则 的 局 限 性 ， 探 
究 使 用 机 器 学 习 的 方式 处 理 API 文档 ， 以 便 在 文档 中 提取 到 更 
多 的 有 效 信息 ， 并 在 此 基础 上 ， 探 究 本 方法 对 于 其 他 编程 语言 
的 适用 性 。 
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